<!-- HTML header for doxygen 1.8.13-->
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.9.2"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>(abstraction-rtos)</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtreedata.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen_style.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td id="projectlogo"><a href="http://www.cypress.com/"><img alt="Logo" src="logo.png"/></a></td>
  <td id="projectalign" style="padding-left: 0.5em;">
   <div id="projectname">(abstraction-rtos)</div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.9.2 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
var searchBox = new SearchBox("searchBox", "search",'Search','.html');
/* @license-end */
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
$(function() {
  initMenu('',true,false,'search.php','Search');
  $(document).ready(function() { init_search(); });
});
/* @license-end */
</script>
<div id="main-nav"></div>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
      <div id="nav-sync" class="sync"></div>
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;" 
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
$(document).ready(function(){initNavTree('index.html',''); initResizable(); });
/* @license-end */
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

<div><div class="header">
  <div class="headertitle"><div class="title">RTOS Abstraction </div></div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p ><a class="anchor" id="md_output_README_doxygen"></a> </p>
<h1><a class="anchor" id="autotoc_md1"></a>
Overview</h1>
<p >The RTOS abstraction layer provides simple RTOS services like threads, semaphores, mutexes, queues, and timers. It is not intended to be a full features RTOS interface, but the provide just enough support to allow for RTOS independent drivers and middleware. This allows middleware applications to be as portable as possible within ModusToolbox™. This library provides a unified API around the actual RTOS. This allows middleware libraries to be written once independent of the RTOS actually selected for the application. The abstraction layer provides access to all the standard RTOS resources listed in the feature section below.</p>
<p >While the primary purpose of the library is for middleware, the abstraction layer can be used by the application code. However, since this API does not provide all RTOS features and the application generally knows what RTOS is being used, this is typically an unnecessary overhead.</p>
<p >All the RTOS abstraction layer functions generally all work the same way. The basic process is:</p><ol type="1">
<li>Include the cyabs_rtos.h header file so that you have access to the RTOS functions.</li>
<li>Declare a variable of the right type (e.g. cy_mutex_t)</li>
<li>Call the appropriate create or initialize function (e.g. <a class="el" href="group__group__abstraction__rtos__mutex.html#ga79fbca5c574d2bc617af90d4bff6c902" title="Create a mutex which can support recursion.">cy_rtos_init_mutex()</a>). Provide it with a reference to the variable that was created in step 2.</li>
<li>Access the RTOS object using one of the access functions. e.g. <a class="el" href="group__group__abstraction__rtos__mutex.html#ga4af2611cb8f459d1b3c2d872a2690bdf" title="Set a mutex.">cy_rtos_set_mutex()</a>.</li>
<li>If you don't need it anymore, free up the pointer with the appropriate de-init function (e.g. <a class="el" href="group__group__abstraction__rtos__mutex.html#ga0f182fcf04af391bd073a2d17c4af716" title="Deletes a mutex.">cy_rtos_deinit_mutex()</a>).</li>
</ol>
<p >NOTE: All these functions need a pointer, so it is generally best to declare these "shared" resources as static global variables within the file that they are used.</p>
<h1><a class="anchor" id="autotoc_md2"></a>
Getting Started</h1>
<p >To use the RTOS Abstraction, simply include a reference to <code>cyabs_rtos.h</code> and update the application's makefile to include the appropriate component. e.g. one of:</p><ul>
<li>COMPONENTS+=RTX</li>
<li>COMPONENTS+=FREERTOS</li>
<li>COMPONENTS+=THREADX</li>
</ul>
<h1><a class="anchor" id="autotoc_md3"></a>
Features</h1>
<ul>
<li>APIs for interacting with common RTOS Features including:<ul>
<li>Threads</li>
<li>Mutexes</li>
<li>Semaphores</li>
<li>Timers</li>
<li>Queues</li>
<li>Events</li>
</ul>
</li>
<li>Implementations are provided for<ul>
<li>FreeRTOS</li>
<li>RTX (CMSIS RTOS)</li>
<li>ThreadX</li>
<li>WICED RTOS</li>
</ul>
</li>
</ul>
<h1><a class="anchor" id="autotoc_md4"></a>
RTOS Configuration Requirements</h1>
<h2><a class="anchor" id="autotoc_md5"></a>
FreeRTOS</h2>
<p >To enable all functionality when using with FreeRTOS, the following configuration options must be enabled in FreeRTOSConfig.h:</p><ul>
<li>configSUPPORT_DYNAMIC_ALLOCATION</li>
<li>configSUPPORT_STATIC_ALLOCATION</li>
<li>configUSE_COUNTING_SEMAPHORES</li>
<li>configUSE_MUTEXES</li>
<li>configUSE_NEWLIB_REENTRANT</li>
<li>configUSE_RECURSIVE_MUTEXES</li>
<li>configUSE_TASK_NOTIFICATIONS</li>
<li>configUSE_TICKLESS_IDLE</li>
<li>configUSE_TIMERS</li>
<li>configUSE_TRACE_FACILITY</li>
<li>INCLUDE_vTaskDelay</li>
<li>INCLUDE_vTaskDelete</li>
<li>INCLUDE_vTaskPrioritySet</li>
<li>INCLUDE_uxTaskPriorityGet</li>
<li>INCLUDE_xTimerPendFunctionCall</li>
<li>INCLUDE_vTaskSuspend</li>
</ul>
<p >Enabling configSUPPORT_STATIC_ALLOCATION requires the application to provide implementations for <code>vApplicationGetIdleTaskMemory</code> and <code>vApplicationGetTimerTaskMemory</code>functions. Weak implementations for these functions are provided as a part of this library. These can be overridden by the application if custom implementations of these functions are desired.<br  />
</p>
<h3><a class="anchor" id="autotoc_md6"></a>
Low Power Configuration</h3>
<p >This library provides an API <code>vApplicationSleep</code> which can be used to enable tickless support in FreeRTOS. In order to enable tickless mode with this API, the following changes need to be made in <code>FreeRTOSConfig.h</code>:</p><ul>
<li>Enables tickless mode with user specified <code>portSUPPRESS_TICKS_AND_SLEEP</code> implementation.<br  />
 <code>#define</code> <code>configUSE_TICKLESS_IDLE 2</code></li>
<li>Hook <code>portSUPPRESS_TICKS_AND_SLEEP</code> macro to <code>vApplicationSleep</code> implementation.<br  />
 <code>#define</code> <code>portSUPPRESS_TICKS_AND_SLEEP( xIdleTime ) vApplicationSleep( xIdleTime )</code></li>
</ul>
<p >In tickless mode <code>vApplicationSleep</code> updates the number of RTOS ticks that have passed since the tick interrupt was stopped using <code>vTaskStepTick</code>, taking into account the sleep/deepsleep latency.</p><ul>
<li><p class="startli">The maximum tickless idle time can be calculated as follow:</p><ul>
<li><code>MaxIdleTime = LPtimerDelay + latency</code> where: <code>latency = PreSleepLatency + PostSleepLatency</code>, <code>LPtimerDelay = xExpectedIdleTime - latency</code>.</li>
</ul>
<p class="startli"><b>Note</b>: The <code>LPtimerDelay</code> represents the duration in which the IP is configured to Wake-up the device. Wake-up can happen before its expiration if one other configured interrupt triggers during this time.</p>
</li>
<li>In case of <code>xExpectedIdleTime &lt;= latency</code> WFI is executed instead, and normal sleep is expected to be reached (SCR-&gt;SLEEPDEEP = 0).</li>
<li>The actual Idle time for which the Systick timer is disabled, is always update in vTaskStepTick to keep the RTOS alwyas up to date, independently from if the tickless sleep is reached or not successfully. The reason for this is to find in the sequence of operations to reach the sleep, the Systick is disabled before the (deep)sleep callbacks are called, so if one of them will not allow (deep)sleep, the ticks for which the check is performed needs to be anyway counted in the RTOS.</li>
</ul>
<p >Functions cy_rtos_scheduler_suspend/cy_rtos_scheduler_resume can be called from ISR but calls need to be paired to restore the saved interrupt status correctly so a structure to save these values has been implemented. The size of this structure can be controlled with CY_RTOS_MAX_SUSPEND_NESTING. This macro is overridable and its default value is 3.</p>
<p >For further details on Low power support in FreeRTOS please refer to documentation <a href="https://www.freertos.org/low-power-tickless-rtos.html">here</a></p>
<h3><a class="anchor" id="autotoc_md7"></a>
Known Limitations</h3>
<p >The cy_rtos_event_* functions accept a 32-bit event as an argument. However, FreeRTOS requires 8-bits(<code>configUSE_16_BIT_TICKS</code> == 1) or 24-bits (<code>configUSE_16_BIT_TICKS</code> == 0) to run successfully. Hence the application should not reference these unsupported bits. Check the FreeRTOS implementation of <code>eventEVENT_BITS_CONTROL_BYTES</code> in event_group.c for internal details.</p>
<h2><a class="anchor" id="autotoc_md8"></a>
RTX / ThreadX</h2>
<p >No specific requirements exist</p>
<h1><a class="anchor" id="autotoc_md9"></a>
Porting Notes</h1>
<p >In order to port to a new environment, the file cyabs_rtos_impl.h must be provided with definitions of some basic types for the abstraction layer. The types expected to be defined are:</p>
<ul>
<li><code>cy_thread_t</code> : typedef from underlying RTOS thread type</li>
<li><code>cy_thread_arg_t</code> : typedef from the RTOS type that is passed to the entry function of a thread.</li>
<li><code>cy_mutex_t</code> : typedef from the underlying RTOS mutex type</li>
<li><code>cy_semaphore_t</code>: typedef from the underlying RTOS semaphore type</li>
<li><code>cy_event_t</code> : typedef from the underlying RTOS event type</li>
<li><code>cy_queue_t</code> : typedef from the underlying RTOS queue type</li>
<li><code>cy_timer_callback_arg_t</code> : typedef from the RTOS type that is passed to the timer callback function</li>
<li><code>cy_timer_t</code> : typedef from the underlying RTOS timer type</li>
<li><code>cy_time_t</code> : count of time in milliseconds</li>
<li><code>cy_rtos_error_t</code> : typedef from the underlying RTOS error type</li>
</ul>
<p >The enum <code>cy_thread_priority_t</code> needs to have the following priority values defined and mapped to RTOS specific values:</p><ul>
<li><code>CY_RTOS_PRIORITY_MIN</code></li>
<li><code>CY_RTOS_PRIORITY_LOW</code></li>
<li><code>CY_RTOS_PRIORITY_BELOWNORMAL</code></li>
<li><code>CY_RTOS_PRIORITY_NORMAL</code></li>
<li><code>CY_RTOS_PRIORITY_ABOVENORMAL</code></li>
<li><code>CY_RTOS_PRIORITY_HIGH</code></li>
<li><code>CY_RTOS_PRIORITY_REALTIME</code></li>
<li><code>CY_RTOS_PRIORITY_MAX</code></li>
</ul>
<p >Finally, the following macros need to be defined for memory allocations:</p><ul>
<li><code>CY_RTOS_MIN_STACK_SIZE</code></li>
<li><code>CY_RTOS_ALIGNMENT</code></li>
<li><code>CY_RTOS_ALIGNMENT_MASK</code></li>
</ul>
<h1><a class="anchor" id="autotoc_md10"></a>
More information</h1>
<ul>
<li><a href="https://infineon.github.io/abstraction-rtos/html/modules.html">API Reference Guide</a></li>
<li><a href="http://www.cypress.com">Cypress Semiconductor, an Infineon Technologies Company</a></li>
<li><a href="https://github.com/infineon">Infineon GitHub</a></li>
<li><a href="https://www.cypress.com/products/modustoolbox-software-environment">ModusToolbox™</a></li>
</ul>
<hr  />
<p> © Cypress Semiconductor Corporation (an Infineon company) or an affiliate of Cypress Semiconductor Corporation, 2019-2022. </p>
</div></div><!-- PageDoc -->
</div><!-- contents -->
</div><!-- doc-content -->
<!-- start footer part
<div id="nav-path" class="navpath">
    <ul>
        <li class="footer">
            Generated for <b>(abstraction-rtos)</b> by <b>Cypress Semiconductor Corporation</b>.
            All rights reserved.
        </li>
    </ul>
</div>
-->
</body>
</html>
